---
title: ButterCMS & Astro
description: ButterCMS를 사용하여 Astro 프로젝트에 콘텐츠 추가
sidebar:
  label: ButterCMS
type: cms
logo: buttercms
stub: false
i18nReady: true
---

import { Steps } from '@astrojs/starlight/components';
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[ButterCMS](https://buttercms.com/)는 프로젝트에 사용할 구조화된 콘텐츠를 게시할 수 있는 헤드리스 CMS 및 블로그 엔진입니다.

## Astro와 통합

:::note
전체 블로그 사이트 예시를 보려면 [Astro + ButterCMS 스타터 프로젝트](https://buttercms.com/starters/astro-starter-project/)를 참조하세요.
:::

이 섹션에서는 [ButterCMS SDK](https://www.npmjs.com/package/buttercms)를 사용하여 데이터를 Astro 프로젝트로 가져옵니다.
시작하려면 다음이 필요합니다.

### 전제 조건

1. **Astro 프로젝트** - 아직 Astro 프로젝트가 없다면 [설치 가이드](/ko/install-and-setup/)를 참조하여 즉시 설치하고 실행할 수 있습니다.

2. **ButterCMS 계정**. 계정이 없다면 무료 평가판에 [가입](https://buttercms.com/join/)할 수 있습니다.

3. **ButterCMS API 토큰** - [설정](https://buttercms.com/settings/) 페이지에서 API 토큰을 찾을 수 있습니다.

### 설정

<Steps>
1. 프로젝트 루트에 `.env` 파일을 만들고 API 토큰을 환경 변수로 추가합니다.

    ```ini title=".env"
    BUTTER_TOKEN=YOUR_API_TOKEN_HERE
    ```

    :::tip
    Astro의 [환경 변수 사용](/ko/guides/environment-variables/) 및 `.env` 파일에 대해 자세히 알아보세요.
    :::

2. ButterCMS SDK를 종속성으로 설치합니다.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```shell
      npm install buttercms
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```shell
      pnpm add buttercms
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```shell
      yarn add buttercms
      ```
      </Fragment>
    </PackageManagerTabs>

3. 프로젝트의 새 `src/lib/` 디렉터리에 `buttercms.js` 파일을 만듭니다.

    ```js title="src/lib/buttercms.js"
    import Butter from "buttercms";

    export const butterClient = Butter(import.meta.env.BUTTER_TOKEN);
    ```
</Steps>

**API 토큰을 사용하여 SDK를 인증하고 프로젝트 전체에서 사용할 수 있도록 내보냅니다.**

### 데이터 가져오기

콘텐츠를 가져오려면 이 클라이언트를 가져오고 해당 `retrieve` 함수 중 하나를 사용하세요.

이 예시에서는 짧은 텍스트 `name`, 숫자 `price` 및 WYSIWYG `description`의 세 가지 필드가 있는 [컬렉션을 검색](https://buttercms.com/docs/api/#retrieve-a-collection)합니다.

```astro title="src/pages/ShopItem.astro"
---
import { butterClient } from "../lib/buttercms";
const response = await butterClient.content.retrieve(["shopitem"]);

interface ShopItem {
	name: string,
	price: number,
	description: string,
}

const items = response.data.data.shopitem as ShopItem[];
---
<body>
	{items.map(item => <div>
		<h2>{item.name} - ${item.price}</h2>
		<p set:html={item.description}></p>
	</div>)}
</body>
```

인터페이스는 필드 타입을 반영합니다. WYSIWYG `description` 필드는 HTML 문자열로 로드되며 [`set:html`](/ko/reference/directives-reference/#sethtml)을 통해 이를 렌더링할 수 있습니다.

마찬가지로 [페이지를 검색](https://buttercms.com/docs/api/#get-a-single-page)하고 해당 필드를 표시할 수 있습니다.

```astro title="src/pages/ShopItem.astro"
---
import { butterClient } from "../lib/buttercms";
const response = await butterClient.page.retrieve("*", "simple-page");
const pageData = response.data.data;

interface Fields {
  seo_title: string,
  headline: string,
  hero_image: string,
}

const fields = pageData.fields as Fields;
---
<html>
  <title>{fields.seo_title}</title>
  <body>
    <h1>{fields.headline}</h1>
    <img src={fields.hero_image} />
  </body>
</html>
```

## 공식 자료

- [Astro + ButterCMS 스타터 프로젝트](https://buttercms.com/starters/astro-starter-project/)
- [전체 ButterCMS API 문서](https://buttercms.com/docs/api/)
- ButterCMS의 [JavaScript 안내서](https://buttercms.com/docs/api-client/javascript/)

## 커뮤니티 자료

- 여러분의 자료를 추가하세요!
